Zendesk Command Line Interface (ZCLI) の開発環境セットアップをしてみた

皆さんは Zendesk Command Line Interface (ZCLI)を使ったことありますか？本ブログでは、ZCLIの開発環境セットアップ方法についてご紹介します。

#Zendesk

Takaaki Kakei

2022.08.14

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

こんにちは、サービスグロースチームの筧です。

ZCLI は Zendesk アプリを開発するためのコマンドラインツールです。ZCLI を使うことで、 Zendesk アプリをローカルでビルド・テスト・パッケージ化できます。別に Zendesk App Tools (ZAT)というものがありますが、これに代わるオープンベータ版のコマンドラインツールです。

Note: The Zendesk Command Line Interface (ZCLI) is in open beta. It is fully supported by Zendesk but may change at any time.

ZCLI is a command-line tool for developing Zendesk apps. You can use ZCLI to build, test, and package your Zendesk apps locally. ZCLI replaces the Zendesk App Tools (ZAT), which are in maintenance mode.

先日、ZCLI の開発環境セットアップのチュートリアルをやったので、その内容についてご紹介します！

やってみた

Using the Zendesk Command Line Interface (ZCLI) | Zendesk Developer Docs

筆者の環境

% sw_vers 
ProductName:    macOS
ProductVersion: 12.2.1
BuildVersion:   21D62

ZCLI のインストールとアップデート

ZCLI requires Node.js 14.17.3 or above.

Node.js の version が 14.17.3 であることを確認します。

% node -v                                                                     
v18.6.0

npm が使えることを確認します。

% npm -v
8.13.2

ZCLI をインストールします。

% npm install @zendesk/zcli -g

インストール後、以下のコマンドでヘルプが表示されたらOKです。

% zcli help

To update ZCLI, run the installation command again. ZCLI warns you if your installed version is out of date.

ZCLI をアップデートしたい場合は、再度インストールのコマンドを実行します。

App configuration file の準備

Setting up new apps | Zendesk Developer Docs

App configuration file はアプリで参照するパラメータを保存する場所です。

% cd {プロジェクトフォルダ}
% touch zcli.apps.config.json

zcli.apps.config.json には、仮で下記内容を保存しておきます。

{
  "parameters": {
    "mySetting": "test value"
  }
}

Profiles の準備

今回は API token を利用して、Profiles を準備します。

When prompted, enter your subdomain, email, and password. If you've disabled password access for your account, use an API token instead. When providing an API token, the username must be in the email@example.com/token format.

% cd {プロジェクトフォルダ}
% zcli login -i
Subdomain: {Zendeskのサブドメイン}
Email: {メールアドレス}/token
Password: ｛api token｝
Successfully logged in.

ローカルには、１つのサブドメインあたり1つのプロファイルを作成できます。更新する場合は都度、loginコマンドを実行します。

Updating a profile ZCLI supports one profile per subdomain. To change the credentials for a subdomain, run the zcli login -i command again. When prompted, enter your new credentials.

準備したプロファイルは list コマンドで確認できます。

% zcli profiles:list                                                        
 Subdomains                   
 ──────────────────────────── 
 {サブドメイン1} <= active

active にしたいサブドメインを切り替えたいときは、以下のコマンドを使います。

zcli profiles:use {subdomain}

プロファイルの削除は2つやり方があります。

# やり方1： 対象のサブドメインをアクティブにしてからログアウト
zcli profiles:use {subdomain}
zcli logout

# やり方2： 対象のサブドメインを指定して削除
zcli profiles:remove {subdomain}

Zendesk app のための starter files を作成

Using the Zendesk Command Line Interface (ZCLI) | Zendesk Developer Docs

今回は、特にオプションを指定せず、starter files を作成します。

% zcli apps:new
Enter a directory name to save the new app (will create the dir if it does not exist): .
Enter this app authors name: kakei
Enter this app authors email: xxxx@yyyyyy
Enter a name for this new app: sample
Successfully created new project .

コマンド実行後のツリー構造は以下です。

% tree
.
├── LICENSE
├── README.md
├── assets
│   ├── iframe.html
│   ├── logo-small.png
│   ├── logo.png
│   └── logo.svg
├── manifest.json
├── translations
│   └── en.json
└── zcli.apps.config.json

Zendesk アプリをローカルでテスト

以下のコマンドで、コンピューターで Zendesk アプリを実行できるローカル Web サーバーを起動します。開発時のアプリのテストやプレビューに便利です。

# zcli apps:server {app_directory}
% zcli apps:server .                                                        

Apps server is running on http://localhost:4567 ?

Add ?zcli_apps=true to the end of your Zendesk URL to load these apps on your Zendesk account.

avtive なサブドメインの環境に、Chromeのシークレットウィンドウでログインして適当なチケットを開きます。その後、対象チケットのURL末尾に、 ?zcli_apps=true を付与します。そして右ペインのアプリアイコンをクリックすると、下図のようにアプリのプレビューができました！